Skip to main content

SurrealDB

Summary​

This document covers the information to gather from SurrealDB in order to configure a Qarbine data service. The data service will use the Qarbine SurrealDB driver. You can define multiple data services that access the same SurrealDB endpoint though with varying credentials. Once a data service is defined, you can manage which Qarbine principals have access to it and its associated SurrealDB data. A Qarbine administrator has visibility to all data services.

Overview​

SurrealDB is an open-source multi-model database that combines document, graph, time-series, relational, vector, search, and geospatial capabilities behind a single SQL-like query language called SurrealQL.

SurrealDB Configuration​

Overview​

Open the SurrealDB console by logging in at https://app.surrealdb.com/signin

Navigate to your SurrealDB dashboard.

  

Confirm SurrealDB is running. Your instance is paused if you see this.

  

Click the “Resume instance” button,

  

Click the “Resume” button,

Determine the Endpoint​

In the upper left click

  

Click the associated SurrealDB Cloud instance.

  

Click the “Instance action” button and then click “Copy hostname”

  

A sample value is

zealous-galaxy-abcdefgh123456789.aws-use1.surreal.cloud

The effective endpoint will have a “wss://” prefix.

Determine Authentication​

SurrealDB has flexible authentication options spanning root, namespace and database levels.
User and password authentication is used for Qarbine interactions with SurrealDB. Click the button shown below in the left hand area

  

Decide on your user. It is highly recommended that the user only have Viewer permissions.

  

Tokens are obtained which may have limited lifespan. To review these settings edit the user as shown below.

  

For more information see https://surrealdb.com/docs/surrealdb/security/authentication#expiration

Qarbine automatically handles token expiration and reauthentication.

Determine Namespace and Any Database​

Based on the Authentication approach above, match up a namespace value. A Qarbine Data Service is always associated with a single SurrealDB namespace. It may optionally be constrained to a single database as describe below via the “Database” entry field.

Qarbine Configuration​

Compute Node Preparation​

Determine which compute node service endpoint you want to run this data access from. That URL will go into the Data Service’s Compute URL field. Its form is “https://domain:port/dispatch”. A sample is shown below.

  

The port number corresponds to a named service endpoint configured on the given target host. For example, the primary compute node usually is set to have a ‘main’ service. That service’s configuration is defined in the ˜./qarbine.service/config/service.main.json file. Inside that file the following driver entry is required

"drivers" :[
 . . .
"./driver/surrealDbDriver.js"
]

The relevant configuration file name for non primary (main) Qarbine compute nodes is service.NAME.json. Remember to have well formed JSON syntax or a startup error is likely to occur. If you end up adding that entry then restart the service via the general command line syntax

pm2 restart <service>

For example,

pm2 restart main

or simply

pm2 restart all

Data Service Definition​

Open the Administration Tool.

Navigate to the Data Services tab.

  

A data service defines on what compute node a query will run by default along with the means to reach to target data. The latter includes which native driver to use along with settings corresponding to that driver. Multiple Data Sources can reference a single Data Service. The details of any one Data Service are thus maintained in one spot and not spread out all over the place in each Data Source. The latter is a maintenance and support nightmare.

To begin adding a data service click

  

On the right hand side enter a data service name and description.

  

Set the Compute URL field based on the identified compute node above. Its form is “https://domain:port/dispatch”. A sample is shown below.

  

Next choose the driver.

  

For the server template enter the endpoint.

  

For the server options use one of the following pattern

authentication = AUTH_LEVEL,
namespace = NAMESPACE, 
database = DATABASE, 
user = USER,
password = PASSWORD,

All are required. The authentication level must be one of root, namespace, or database.

For example,

  

You can reference environment variables using the syntax %NAME%. Any strings should be quoted and the key\value pairs separated by commas.

To restrict the “Database” drop down in the Data Source Designer and other tools specify a name in the “Database” field. This value is independent of the server options authentication value above.

  

Test your settings by clicking on the toolbar image highlighted below.

  

When no “database” has been specified the result should be

  

Save the Data Service by clicking on the image highlighted below.

  

The data service will be known at the next log on time. Next, see the SurrealDB query interaction and any tutorial for information on interacting with SurrealDB from Qarbine.

Authentication Credential LIfecycle​

Qarbine keeps SurrealDB connections authenticated by automatically renewing credentials before they expire. It tracks both the short‑lived authentication token and the longer‑lived server session that SurrealDB establishes from that token, then proactively refreshes based on whichever expires first. If either the token’s expiry time or the session’s expiry time is approaching, Qarbine transparently re‑authenticates in the background and updates the connection, so long‑running workloads continue without manual sign‑ins or intermittent ‘unauthorized’ errors.

The renewal timeframe is 5 seconds before the earlier of the 2 expiration dates. It is at least 30 seconds in the future.